Documentation/rest-api-changes.txt

Gerrit Code Review - '/changes/' REST API
=========================================

This page describes the change related REST endpoints.
Please also take note of the general information on the
link:rest-api.html[REST API].

Endpoints
---------

[[list-changes]]
GET /changes/ (Query Changes)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Queries changes visible to the caller. The query string must be
provided by the `q` parameter. The `n` parameter can be used to limit
the returned results.

As result a list of link:#change-info[ChangeInfo] entries is returned.
The change output is sorted by the last update time, most recently
updated to oldest updated.

Query for open changes of watched projects:

.Request
----
 GET /changes/?q=status:open+is:watched&n=2 HTTP/1.0
----

.Response
----
 HTTP/1.1 200 OK
 Content-Disposition: attachment
 Content-Type: application/json;charset=UTF-8

 )]}'
 {
 "kind": "gerritcodereview#change",
 "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
 "project": "demo",
 "branch": "master",
 "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
 "subject": "One change",
 "status": "NEW",
 "created": "2012-07-17 07:18:30.854000000",
 "updated": "2012-07-17 07:19:27.766000000",
 "reviewed": true,
 "mergeable": true,
 "_sortkey": "001e7057000006dc",
 "_number": 1756,
 "owner": {
 "name": "John Doe"
 },
 },
 {
 "kind": "gerritcodereview#change",
 "id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501",
 "project": "demo",
 "branch": "master",
 "change_id": "I09c8041b5867d5b33170316e2abc34b79bbb8501",
 "subject": "Another change",
 "status": "NEW",
 "created": "2012-07-17 07:18:30.884000000",
 "updated": "2012-07-17 07:18:30.885000000",
 "mergeable": true,
 "_sortkey": "001e7056000006dd",
 "_number": 1757,
 "owner": {
 "name": "John Doe"
 },
 "_more_changes": true
 }
----

If the `n` query parameter is supplied and additional changes exist
that match the query beyond the end, the last change object has a
`_more_changes: true` JSON field set. Callers can resume a query with
the `N` query parameter, supplying the last change's `_sortkey` field
as the value. When going in the reverse direction with the `P` query
parameter a `_more_changes: true` is put in the first change object if
there are results *before* the first change returned.

Clients are allowed to specify more than one query by setting the `q`
parameter multiple times. In this case the result is an array of
arrays, one per query in the same order the queries were given in.

.Query for the 25 most recent open changes of the projects that you watch
****
get::/changes/?q=status:open+is:watched&n=25
****

Query that retrieves changes for a user's dashboard:

.Request
----
 GET /changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS HTTP/1.0
----

.Response
----
 HTTP/1.1 200 OK
 Content-Disposition: attachment
 Content-Type: application/json;charset=UTF-8

 )]}'
 [
 [
 {
 "kind": "gerritcodereview#change",
 "id": "demo~master~Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
 "project": "demo",
 "branch": "master",
 "change_id": "Idaf5e098d70898b7119f6f4af5a6c13343d64b57",
 "subject": "One change",
 "status": "NEW",
 "created": "2012-07-17 07:18:30.854000000",
 "updated": "2012-07-17 07:19:27.766000000",
 "reviewed": true,
 "mergeable": true,
 "_sortkey": "001e7057000006dc",
 "_number": 1756,
 "owner": {
 "name": "John Doe"
 },
 "labels": {
 "Verified": {},
 "Code-Review": {}
 }
 }
 ],
 [],
 []
 ]
----

.Query the changes for your user dashboard
****
get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS
****

Additional fields can be obtained by adding `o` parameters, each
option requires more database lookups and slows down the query
response time to the client so they are generally disabled by
default. Optional fields are:

[[labels]]
--
* `LABELS`: a summary of each label required for submit, and
 approvers that have granted (or rejected) with that label.
--

[[detailed-labels]]
--
* `DETAILED_LABELS`: detailed label information, including numeric
 values of all existing approvals, recognized label values, values
 permitted to be set by the current user, and reviewers that may be
 removed by the current user.
--

[[current-revision]]
--
* `CURRENT_REVISION`: describe the current revision (patch set)
 of the change, including the commit SHA-1 and URLs to fetch from.
--

[[all-revisions]]
--
* `ALL_REVISIONS`: describe all revisions, not just current.
--

[[current-commit]]
--
* `CURRENT_COMMIT`: parse and output all header fields from the
 commit object, including message. Only valid when the current
 revision or all revisions are selected.
--

[[all-commits]]
--
* `ALL_COMMITS`: parse and output all header fields from the
 output revisions. If only `CURRENT_REVISION` was requested
 then only the current revision's commit data will be output.
--

[[current-files]]
--
* `CURRENT_FILES`: list files modified by the commit, including
 basic line counts inserted/deleted per file. Only valid when
 the current revision or all revisions are selected.
--

[[all-files]]
--
* `ALL_FILES`: list files modified by the commit, including
 basic line counts inserted/deleted per file. If only the
 `CURRENT_REVISION` was requested the only that commit's
 modified files will be output.
--

[[detailed-accounts]]
--
* `DETAILED_ACCOUNTS`: include `_account_id` and `email` fields when
 referencing accounts.
--

.Request
----
 GET /changes/?q=97&o=CURRENT_REVISION&o=CURRENT_COMMIT&o=CURRENT_FILES HTTP/1.0
----

.Response
----
 HTTP/1.1 200 OK
 Content-Disposition: attachment
 Content-Type: application/json;charset=UTF-8

 )]}'
 [
 {
 "kind": "gerritcodereview#change",
 "id": "demo~master~I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
 "project": "gerrit",
 "branch": "master",
 "change_id": "I7ea46d2e2ee5c64c0d807677859cfb7d90b8966a",
 "subject": "Use an EventBus to manage star icons",
 "status": "NEW",
 "created": "2012-04-25 00:52:25.580000000",
 "updated": "2012-04-25 00:52:25.586000000",
 "mergeable": true,
 "_sortkey": "001c9bf400000061",
 "_number": 97,
 "owner": {
 "name": "Shawn Pearce"
 },
 "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c",
 "revisions": {
 "184ebe53805e102605d11f6b143486d15c23a09c": {
 "_number": 1,
 "fetch": {
 "git": {
 "url": "git://localhost/gerrit",
 "ref": "refs/changes/97/97/1"
 },
 "http": {
 "url": "http://127.0.0.1:8080/gerrit",
 "ref": "refs/changes/97/97/1"
 }
 },
 "commit": {
 "parents": [
 {
 "commit": "1eee2c9d8f352483781e772f35dc586a69ff5646",
 "subject": "Migrate contributor agreements to All-Projects."
 }
 ],
 "author": {
 "name": "Shawn O. Pearce",
 "email": "sop@google.com",
 "date": "2012-04-24 18:08:08.000000000",
 "tz": -420
 },
 "committer": {
 "name": "Shawn O. Pearce",
 "email": "sop@google.com",
 "date": "2012-04-24 18:08:08.000000000",
 "tz": -420
 },
 "subject": "Use an EventBus to manage star icons",
 "message": "Use an EventBus to manage star icons\n\nImage widgets that need to ..."
 },
 "files": {
 "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": {
 "lines_deleted": 8
 },
 "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": {
 "lines_inserted": 1
 },
 "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": {
 "lines_inserted": 11,
 "lines_deleted": 19
 },
 "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": {
 "lines_inserted": 23,
 "lines_deleted": 20
 },
 "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": {
 "status": "D",
 "lines_deleted": 139
 },
 "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": {
 "status": "A",
 "lines_inserted": 204
 },
 "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": {
 "lines_deleted": 9
 }
 }
 }
 }
 }
 ]
----

[[get-change]]
GET /changes/\{change-id\} (Get Change)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves a change.

.Request
----
 GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0
----

As response a link:#change-info[ChangeInfo] entity is returned that
describes the change.

.Response
----
 HTTP/1.1 200 OK
 Content-Disposition: attachment
 Content-Type: application/json;charset=UTF-8

 )]}'
 {
 "kind": "gerritcodereview#change",
 "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
 "project": "myProject",
 "branch": "master",
 "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
 "subject": "Implementing Feature X",
 "status": "NEW",
 "created": "2013-02-01 09:59:32.126000000",
 "updated": "2013-02-21 11:16:36.775000000",
 "reviewed": true,
 "mergeable": true,
 "_sortkey": "0023412400000f7d",
 "_number": 3965,
 "owner": {
 "name": "John Doe"
 }
 }
----

[[get-change-detail]]
GET /changes/\{change-id\}/detail (Get Change Detail)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves a change with link:#labels[labels], link:#detailed-labels[
detailed labels] and link:#detailed-accounts[detailed accounts].

.Request
----
 GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/detail HTTP/1.0
----

As response a link:#change-info[ChangeInfo] entity is returned that
describes the change.

.Response
----
 HTTP/1.1 200 OK
 Content-Disposition: attachment
 Content-Type: application/json;charset=UTF-8

 )]}'
 {
 "kind": "gerritcodereview#change",
 "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
 "project": "myProject",
 "branch": "master",
 "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
 "subject": "Implementing Feature X",
 "status": "NEW",
 "created": "2013-02-01 09:59:32.126000000",
 "updated": "2013-02-21 11:16:36.775000000",
 "reviewed": true,
 "mergeable": true,
 "_sortkey": "0023412400000f7d",
 "_number": 3965,
 "owner": {
 "_account_id": 1000096,
 "name": "John Doe",
 "email": "john.doe@example.com"
 },
 "labels": {
 "Verified": {
 "all": [
 {
 "value": 0,
 "_account_id": 1000096,
 "name": "John Doe",
 "email": "john.doe@example.com"
 },
 {
 "value": 0,
 "_account_id": 1000097,
 "name": "Jane Roe",
 "email": "jane.roe@example.com"
 }
 ],
 "values": {
 "-1": "Fails",
 " 0": "No score",
 "+1": "Verified"
 }
 },
 "Code-Review": {
 "recommended": {
 "_account_id": 1000097,
 "name": "Jane Roe",
 "email": "jane.roe@example.com"
 },
 "disliked": {
 "_account_id": 1000096,
 "name": "John Doe",
 "email": "john.doe@example.com"
 },
 "all": [
 {
 "value": -1,
 "_account_id": 1000096,
 "name": "John Doe",
 "email": "john.doe@example.com"
 },
 {
 "value": 1,
 "_account_id": 1000097,
 "name": "Jane Roe",
 "email": "jane.roe@example.com"
 }
 ]
 "values": {
 "-2": "Do not submit",
 "-1": "I would prefer that you didn\u0027t submit this",
 " 0": "No score",
 "+1": "Looks good to me, but someone else must approve",
 "+2": "Looks good to me, approved"
 }
 }
 },
 "permitted_labels": {
 "Verified": [
 "-1",
 " 0",
 "+1"
 ],
 "Code-Review": [
 "-2",
 "-1",
 " 0",
 "+1",
 "+2"
 ]
 },
 "removable_reviewers": [
 {
 "_account_id": 1000096,
 "name": "John Doe",
 "email": "john.doe@example.com"
 },
 {
 "_account_id": 1000097,
 "name": "Jane Roe",
 "email": "jane.roe@example.com"
 }
 ]
 }
----

[[get-topic]]
GET /changes/\{change-id\}/topic (Get Topic)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieves the topic of a change.

.Request
----
 GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
----

.Response
----
 HTTP/1.1 200 OK
 Content-Disposition: attachment
 Content-Type: application/json;charset=UTF-8

 )]}'
 "Documentation"
----

If the change does not have a topic an empty string is returned.

[[set-topic]]
PUT /changes/\{change-id\}/topic (Set Topic)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the topic of a change.

The new topic must be provided in the request body inside a
link:#topic-input[TopicInput] entity.

.Request
----
 PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
 Content-Type: application/json;charset=UTF-8

 {
 "topic": "Documentation"
 }
----

As response the new topic is returned.

.Response
----
 HTTP/1.1 200 OK
 Content-Disposition: attachment
 Content-Type: application/json;charset=UTF-8

 )]}'
 "Documentation"
----

If the topic was deleted the response is "`204 No Content`".

[[delete-topic]]
DELETE /changes/\{change-id\}/topic (Delete Topic)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Deletes the topic of a change.

The request body does not need to include a link:#topic-input[
TopicInput] entity if no review comment is added.

Please note that some proxies prohibit request bodies for DELETE
requests. In this case, if you want to specify a commit message, use
link:#set-topic[PUT] to delete the topic.

.Request
----
 DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
----

.Response
----
 HTTP/1.1 204 No Content
----


[[ids]]
IDs
---

[[change-id]]
\{change-id\}
~~~~~~~~~~~~~
Identifier that uniquely identifies one change.

This can be:

* an ID of the change in the format "'$$<project>~<branch>~<Change-Id>$$'",
 where for the branch the `refs/heads/` prefix can be omitted
 ("$$myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940$$")
* a Change-Id if it uniquely identifies one change
 ("I8473b95934b5732ac55d26311a706c9c2bde9940")
* a legacy numeric change ID ("4247")


[[json-entities]]
JSON Entities
-------------

[[account-info]]
AccountInfo
~~~~~~~~~~~
The `AccountInfo` entity contains information about an account.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`_account_id` ||The numeric ID of the account.
|`name` |optional|The full name of the user. +
Only set if link:#detailed-accounts[detailed account information] is
requested.
|`email` |optional|
The email address the user prefers to be contacted through. +
Only set if link:#detailed-accounts[detailed account information] is
requested.
|===========================

[[approval-info]]
ApprovalInfo
~~~~~~~~~~~~
The `ApprovalInfo` entity contains information about an approval from a
user for a label on a change.

`ApprovalInfo` has the same fields as link:#account-info[AccountInfo].
In addition `ApprovalInfo` has the following fields:

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`value` ||The vote that the user has given for the label.
|===========================

[[change-info]]
ChangeInfo
~~~~~~~~~~
The `ChangeInfo` entity contains information about a change.

[options="header",width="50%",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`kind` ||`gerritcodereview#change`
|`id` ||
The ID of the change in the format "'<project>\~<branch>~<Change-Id>'",
where project, branch and Change-Id are URL encoded. For branch the
`refs/heads/` prefix is omitted.
|`project` ||The name of the project.
|`branch` ||
The name of the target branch. +
The `refs/heads/` prefix is omitted.
|`topic` |optional|The topic to which this change belongs.
|`change_id` ||The Change-Id of the change.
|`subject` ||
The subject of the change (header line of the commit message).
|`status` ||
The status of the change (`NEW`, `SUBMITTED`, `MERGED`, `ABANDONED`,
`DRAFT`).
|`created` ||
The link:rest-api.html#timestamp[timestamp] of when the change was
created.
|`updated` ||
The link:rest-api.html#timestamp[timestamp] of when the change was last
updated.
|`starred` |not set if `false`|
Whether the calling user has starred this change.
|`reviewed` |not set if `false`|
Whether the change was reviewed by the calling user.
|`mergeable` ||Whether the change is mergeable.
|`_sortkey` ||The sortkey of the change.
|`_number` ||The legacy numeric ID of the change.
|`owner` ||
The owner of the change as an link:#account-info[AccountInfo] entity.
|`labels` |optional|
The labels of the change as a map that maps the label names to
link:#label-info[LabelInfo] entries. +
Only set if link:#labels[labels] or link:#detailed-labels[detailed
labels] are requested.
|`permitted_labels` |optional|
A map of the permitted labels that maps a label name to the list of
values that are allowed for that label. +
Only set if link:#detailed-labels[detailed labels] are requested.
|`removable_reviewers`|optional|
The reviewers that can be removed by the calling user as a list of
link:#account-info[AccountInfo] entities. +
Only set if link:#detailed-labels[detailed labels] are requested.
|`current_revision` |optional|
The commit ID of the current patch set of this change. +
Only set if link:#current-revision[the current revision] is requested
or if link:#all-revisions[all revisions] are requested.
|`revisions` |optional|
All patch sets of this changes as a map that maps the commit ID of the
patch set to a link:#revision-info[RevisionInfo] entity. +
Only set if link:#all-revisions[all revisions] are requested.
|`_more_changes` |optional, not set if `false`|
Whether the query would deliver more results if not limited. +
Only set on either the last or the first change that is returned.
|==================================

[[commit-info]]
CommitInfo
~~~~~~~~~~
The `CommitInfo` entity contains information about a commit.

[options="header",width="50%",cols="1,6"]
|==========================
|Field Name |Description
|`commit` |The commit ID.
|`parent` |
The parent commits of this commit as a list of
link:#commit-info[CommitInfo] entities.
|`author` |The author of the commit as a
link:#git-person-info[GitPersonInfo] entity.
|`committer` |The committer of the commit as a
link:#git-person-info[GitPersonInfo] entity.
|`subject` |
The subject of the commit (header line of the commit message).
|`message` |The commit message.
|==========================

[[fetch-info]]
FetchInfo
~~~~~~~~~
The `FetchInfo` entity contains information about how to fetch a patch
set via a certain protocol.

[options="header",width="50%",cols="1,6"]
|==========================
|Field Name |Description
|`url` |The URL of the project.
|`ref` |The ref of the patch set.
|==========================

[[file-info]]
FileInfo
~~~~~~~~
The `FileInfo` entity contains information about a file in a patch set.

[options="header",width="50%",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`status` |optional|
The status of the file ("`A`"=Added, "`D`"=Deleted, "`R`"=Renamed,
"`C`"=Copied, "`W`"=Rewritten). +
Not set if the file was Modified ("`M`").
|`binary` |not set if `false`|Whether the file is binary.
|`old_path` |optional|
The old file path. +
Only set if file was renamed or copied.
|`lines_inserted`|optional|
Number of inserted lines. +
Not set for binary files or if no lines were inserted.
|`lines_deleted` |optional|
Number of deleted lines. +
Not set for binary files or if no lines were deleted.
|=============================

[[git-person-info]]
GitPersonInfo
~~~~~~~~~~~~~
The `GitPersonInfo` entity contains information about the
author/committer of a commit.

[options="header",width="50%",cols="1,6"]
|==========================
|Field Name |Description
|`name` |The name of the author/committer.
|`email` |The email address of the author/committer.
|`date` |The link:rest-api.html#timestamp[timestamp] of when
this identity was constructed.
|`tz` |The timezone offset from UTC of when this identity was
constructed.
|==========================

[[label-info]]
LabelInfo
~~~~~~~~~
The `LabelInfo` entity contains information about a label on a change.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`approved` |optional|The user who approved this label on the change
as a link:#account-info[AccountInfo] entity. +
Only set if link:#labels[labels] are requested.
|`rejected` |optional|The user who rejected this label on the change
as a link:#account-info[AccountInfo] entity. +
Only set if link:#labels[labels] are requested.
|`recommended` |optional|The user who recommended this label on the
change as a link:#account-info[AccountInfo] entity. +
Only set if link:#labels[labels] are requested.
|`disliked` |optional|The user who disliked this label on the change
as a link:#account-info[AccountInfo] entity. +
Only set if link:#labels[labels] are requested.
|`value` |optional|The voting value of the user who
recommended/disliked this label on the change if it is not
"`+1`"/"`-1`". +
Only set if link:#labels[labels] are requested.
|`optional` |not set if `false`|
Whether the label is optional. Optional means the label may be set, but
it's neither necessary for submission nor does it block submission if
set.
|`all` |optional|List of all approvals for this label as a list
of link:#approval-info[ApprovalInfo] entities. +
Only set if link:#detailed-labels[detailed labels] are requested.
|`values` |optional|A map of all values that are allowed for this
label. The map maps the values ("`-2`", "`-1`", " `0`", "`+1`", "`+2`")
to the value descriptions. +
Only set if link:#detailed-labels[detailed labels] are requested.
|===========================

[[revision-info]]
RevisionInfo
~~~~~~~~~~~~
The `RevisionInfo` entity contains information about a patch set.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`draft` |not set if `false`|Whether the patch set is a draft.
|`_number` ||The patch set number.
|`fetch` ||
Information about how to fetch this patch set. The fetch information is
provided as a map that maps the protocol name ("`git`", "`http`",
"`ssh`") to link:#fetch-info[FetchInfo] entities.
|`commit` ||The commit of the patch set as
link:#commit-info[CommitInfo] entity.
|`files` ||
The files of the patch set as a map that maps the file names to
link:#file-info[FileInfo] entities.
|===========================

[[topic-input]]
TopicInput
~~~~~~~~~~
The `TopicInput` entity contains information for setting a topic.

[options="header",width="50%",cols="1,^1,5"]
|===========================
|Field Name ||Description
|`topic` |optional|The topic. +
The topic will be deleted if not set.
|`message` |optional|
Message to be added as review comment to the change when setting the
topic.
|===========================


GERRIT
------
Part of link:index.html[Gerrit Code Review]